Jenkins Kata 2: Build Steps

Learn about adding a build step and the associated result codes.

Jenkins jobs execute build steps. Build steps can be general-purpose scripts or custom steps designed for a specific purpose. This kata will show us how to configure the basic steps in a job.

Step 1: Add a build step#

To execute a build step that writes the build number to a file.

  • Click “Configure.”
  • Click the “Build Steps” tab.
  • Click “Add build step.”
  • Click “Execute shell.”
  • Enter the following code into the “Command” field:
  • Click “Save.”
Click the "Configure" tab
Click the "Configure" tab
Click "Execute shell"
Click "Execute shell"
The "Execute shell" command field
The "Execute shell" command field

Commands

Command / Parameter

Description

echo

This writes text to standard output.

Build ${BUILD_NUMBER} at $(date)

This is the text to write out.

  • `Build` and `at` are text.
  • ${BUILD_NUMBER}: This is a Jenkins environment variable that's set to the ID of the running build.
  • $(date): This is an environment variable that returns the current date.

This script simply appends a new line, including the build number and the current date, to the buildlog.txt file in the workspace.

The “Execute shell” build step is one of the actions that Jenkins can perform as part of a job. The shell build step can execute any shell script, which makes it one of the most flexible available in Jenkins. Custom, purpose-built build steps can be added to Jenkins by installing a plugin, which we’ll see later.

To run the build:

  • Click “Build Now.”
  • Click “Workspace.”
  • Click buildlog.txt.
Workspace display
Workspace display
The "buildlog.txt" file
The "buildlog.txt" file

The shell command configured in the previous step now appends a new line to the buildlog.txt file each time the job runs. This is a trivial example of the actions that can be automated through a Jenkins job.

Step 2: Build step result codes#

To add a shell build step that fails the job:

  • Click the “Back” button.
  • Click “Configure” on the left.
  • Click the “Build Steps” tab.
Click "Configure"
Click "Configure"
The "Build" tab
The "Build" tab
  • Click “Add build step.”
  • Select “Execute shell.”
Select "Execute shell" to add a build step
Select "Execute shell" to add a build step
  • Enter exit 1 into the “Command” field.

  • Click “Save.”

Entering the command in the "Command" field
Entering the command in the "Command" field

To run the job:

  • Click “Build Now.”
Click "Build Now"
Click "Build Now"

All programs return a numerical result code to the OS when they terminate (exit). By convention, a zero means success or no errors. Also by convention, any nonzero result code is interpreted as some type of failure. This job now fails because the execute script build step returns a nonzero result.

This is how a typical CI process works: Each step in the chain of automated actions must succeed for the process to continue. If there are faults in any step along the way, the system flags a failure, stops the process, and alerts the user that something is wrong. If we return to the Jenkins Dashboard, we’ll see that this job now has a less-than-sunny status:

Build failed
Build failed

Constant feedback coming from a CI process allows development teams to address code or build errors immediately rather than allowing problems to pile up. Errors in small code changes are easier to diagnose than errors buried in large changes. The earlier faults and errors are discovered, the cheaper they are to fix. Small changes should be integrated as often as possible to maintain a constant flow of work.

To modify the build step and run the job again:

  • Click “Configure” on the left.
  • Modify the build step added in the previous step:
    • Enter exit 0 into the “Command” field.
    • Click “Save.”
    • Click “Build Now.”
Build succeeded after modifying the build step
Build succeeded after modifying the build step

The return code is now zero, so the build succeeds once again.

Jenkins Kata 1: Create a Job

Jenkins Kata 3: Automated Testing